packages/stack-shared/src/interface/server-interface.ts (1)

662-671: Nit: omit undefined in request body and keep header casing consistent

Use filterUndefined to avoid serializing undefined, and match header casing used elsewhere.

Apply:

       {
         method: "POST",
         headers: {
-          "Content-Type": "application/json"
+          "content-type": "application/json"
         },
-        body: JSON.stringify({
-          email: options.email,
-          team_id: options.teamId,
-          callback_url: options.callbackUrl,
-          permission_ids: options.permissionIds,
-        }),
+        body: JSON.stringify(filterUndefined({
+          email: options.email,
+          team_id: options.teamId,
+          callback_url: options.callbackUrl,
+          permission_ids: options.permissionIds,
+        })),
       },

docs/templates/sdk/types/team-profile.mdx (1)

54-66: Clarify whether permissionIds are direct vs. effective permissions and link to role-permissions

Add a brief note indicating if these are direct grants only (not inherited) and link to the role-permissions endpoint doc for mapping IDs to roles.

docs/templates/sdk/types/team.mdx (2)

207-213: Document the new permissionIds option in Parameters

Add a ParamField entry so readers see the option outside the signature.

Apply:

           <ParamField path="callbackUrl" type="string">
             The URL where users will be redirected after accepting the team invitation.
             
             Required when calling `inviteUser()` in the server environment since the URL cannot be automatically determined.
             
             Example: `https://your-app-url.com/handler/team-invitation`
           </ParamField>
+          <ParamField path="permissionIds" type="string[]">
+            Optional list of permission IDs to grant upon acceptance. Omit to use the project's default role.
+          </ParamField>

---

324-326: Keep "Returns" text consistent with signature (include permissionIds)

The Signature includes permissionIds, but the "Returns" text above still omits it.

Apply:

-      `Promise<{ id: string, email: string, expiresAt: Date }[]>`
+      `Promise<{ id: string, email: string, expiresAt: Date, permissionIds: string[] }[]>`

apps/backend/src/app/api/latest/team-invitations/crud.tsx (1)

56-57: Prefer nullish coalescing over logical OR for defaulting

Use ?? to default only when undefined/null.

Apply:

-          permission_ids: code.data.permission_ids || [],
+          permission_ids: code.data.permission_ids ?? [],

packages/template/src/lib/stack-app/apps/interfaces/client-app.ts (1)

57-57: Ensure return shape aligns with backend payload

Confirm the backend route returns contained_permission_ids and is_paginated: false exactly as typed here, and consider promoting this response shape to a shared exported type in stack-shared to avoid drift.

Apply this diff if you want to centralize the type:

-    getTeamRolePermissions(): Promise<{ items: { id: string, description?: string, contained_permission_ids: string[] }[], is_paginated: false }>,
+    getTeamRolePermissions(): Promise<RolePermissionsList>,

(With RolePermissionsList introduced under stack-shared and imported here.)

packages/template/src/components-page/account-settings/teams/team-member-list-section.tsx (1)

24-52: Localize role labels and avoid raw IDs in UI

• Wrap “Admin”/“Member” with t(...).
• Avoid showing raw role IDs; prefer mapping via getTeamRolePermissions() (id → human label), falling back to t("Member").

-  const userRoles = useMemo(() => {
+  const userRoles = useMemo(() => {
     const rolesMap = new Map<string, string>();
-
     for (const user of users) {
       // Use permission_ids directly from teamProfile
       const permissionIds = user.teamProfile.permission_ids || [];
       // Filter out $-prefixed permissions
       const filteredPermissions = permissionIds.filter((id: string) => !id.startsWith('$'));
       // Find matching role based to permission IDs
-      let roleName = "Member";
+      let roleName = t("Member");
       if (filteredPermissions.length > 0) {
         const roleId = filteredPermissions[0];
         if (roleId === 'team_admin') {
-          roleName = "Admin";
+          roleName = t("Admin");
         } else if (roleId === 'team_member') {
-          roleName = "Member";
+          roleName = t("Member");
         } else {
-          roleName = roleId;
+          roleName = roleId; // TODO: map via getTeamRolePermissions() description/name if available
         }
       }
       rolesMap.set(user.id, roleName);
     }
     return rolesMap;
-  }, [users]);
+  }, [users, t]);

If you want, I can wire in getTeamRolePermissions() to replace the raw ID fallback.

apps/backend/src/app/api/latest/team-invitations/send-code/route.tsx (1)

52-57: Normalize permission_ids before embedding into the code

Dedup to reduce redundant work downstream and keep payload minimal.

-    const codeObj = await teamInvitationCodeHandler.sendCode({
+    const codeObj = await teamInvitationCodeHandler.sendCode({
       tenancy: auth.tenancy,
       data: {
         team_id: body.team_id,
-        permission_ids: body.permission_ids || [],
+        permission_ids: Array.from(new Set(body.permission_ids ?? [])),
       },

apps/backend/src/app/api/latest/team-member-profiles/crud.tsx (3)

82-92: Eliminate N+1 permission queries.

This does one findMany per member. Batch once and group by (teamId, projectUserId) to cut roundtrips and improve latency.

Example replacement:

-      const permissions = await Promise.all(db.map(async (member) => {
-        const perms = await tx.teamMemberDirectPermission.findMany({
-          where: {
-            tenancyId: auth.tenancy.id,
-            projectUserId: member.projectUserId,
-            teamId: member.teamId,
-          },
-          select: { permissionId: true },
-        });
-        return perms.map(p => p.permissionId);
-      }));
+      const keys = db.map(m => `${m.teamId}:${m.projectUserId}`);
+      const permsAll = await tx.teamMemberDirectPermission.findMany({
+        where: {
+          tenancyId: auth.tenancy.id,
+          projectUserId: { in: db.map(m => m.projectUserId) },
+          teamId: { in: db.map(m => m.teamId) },
+        },
+        select: { permissionId: true, teamId: true, projectUserId: true },
+      });
+      const permsMap = new Map<string, string[]>();
+      for (const p of permsAll) {
+        const k = `${p.teamId}:${p.projectUserId}`;
+        (permsMap.get(k) ?? permsMap.set(k, []).get(k)!).push(p.permissionId);
+      }
+      const permissions = keys.map(k => permsMap.get(k) ?? []);

---

94-99: Consider using user signup time as fallback, not membership createdAt.

getUsersLastActiveAtMillis expects a per-user signup/time fallback. Passing teamMember.createdAt may skew “last active” for older users who joined a team later. Prefer projectUser.createdAt.

-      const lastActiveAtMillis = await getUsersLastActiveAtMillis(auth.project.id, auth.branchId, db.map(user => user.projectUserId), db.map(user => user.createdAt));
+      const lastActiveAtMillis = await getUsersLastActiveAtMillis(
+        auth.project.id,
+        auth.branchId,
+        db.map(u => u.projectUserId),
+        db.map(u => u.projectUser.createdAt),
+      );

---

21-23: Optional: stabilize permission_ids ordering.

Sort permission_ids for deterministic output to reduce cache churn and flakey UI diffs.

-    permission_ids: permissionIds,
+    permission_ids: [...permissionIds].sort(),

docs/concepts/role-based-team-invitations.mdx (1)

7-12: Minor grammar/polish.

• “ability to:” → keep, but ensure each bullet is parallel (verb form).
• Consider “granular access control by letting you define exactly which permissions an invited user should have upon joining.”

packages/template/src/components-page/account-settings/teams/team-member-invitation-section.tsx (3)

39-45: Reduce console noise and localize labels; minor cleanup.

• Drop dev console logs.
• Localize “Admin”/“Member” strings via t().

Apply:

-        console.log('Fetching role permissions...');
         const response = await stackApp.getTeamRolePermissions();
-        console.log('Role permissions fetched:', response.items);
         setRolePermissions(response.items);
@@
-      console.log('No permissionIds provided, returning default');
       return t("Default member role");
@@
-      if (roleId === 'team_admin') return 'Admin';
-      if (roleId === 'team_member') return 'Member';
+      if (roleId === 'team_admin') return t('Admin');
+      if (roleId === 'team_member') return t('Member');
@@
-    if (firstPermissionId === 'team_admin') return 'Admin';
-    if (firstPermissionId === 'team_member') return 'Member';
+    if (firstPermissionId === 'team_admin') return t('Admin');
+    if (firstPermissionId === 'team_member') return t('Member');
@@
-                      {permission.id === 'team_admin' ? 'Admin' :
-                        permission.id === 'team_member' ? 'Member' :
+                      {permission.id === 'team_admin' ? t('Admin') :
+                        permission.id === 'team_member' ? t('Member') :
                         permission.id}

Also applies to: 55-57, 216-219, 76-79, 83-86

---

66-71: Micro-optimization: use Set for membership checks instead of a Map-to-self.

Current roleMap maps id->id, then you .get to test presence. A Set is clearer.

Apply:

-    // Map permission IDs to their IDs (instead of descriptions)
-    const roleMap = new Map(rolePermissions.map(role => [role.id, role.id]));
+    // Fast membership check of known role IDs
+    const roleIds = new Set(rolePermissions.map(role => role.id));
@@
-    const matchingRoles = filteredPermissionIds.map(id => roleMap.get(id)).filter(Boolean);
+    const matchingRoles = filteredPermissionIds.filter(id => roleIds.has(id));

---

35-49: Duplicate fetching of role permissions; consider a shared hook or prop-drilling.

Both components fetch the same data separately. Extract a useTeamRolePermissions() hook (with memoized cache) or fetch once in the parent and pass down.

I can sketch a small useTeamRolePermissions() hook backed by a simple in-memory cache to avoid duplicate network calls. Want me to add it?

Also applies to: 153-165

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (3)

656-657: Defensive default for permission_ids.

If older backends omit permission_ids, this will be undefined and violate TeamMemberProfile’s string[] type. Default to [].

Apply:

-        permission_ids: crud.permission_ids,
+        permission_ids: crud.permission_ids ?? [],

---

666-667: Match invitation shape defensively.

Same rationale as above for invitations.

Apply:

-      permissionIds: crud.permission_ids,
+      permissionIds: crud.permission_ids ?? [],

---

1438-1457: Consider lightweight validation/caching for role-permissions; drop unnecessary header.

• GET doesn’t need Content-Type.
• Optional: add a small cache to avoid refetching per component mount; or validate the expected shape to fail fast.

Apply minimal cleanup:

-      {
-        method: "GET",
-        headers: {
-          "Content-Type": "application/json",
-        },
-      },
+      { method: "GET" },

If you want, I can add a createCacheBySession for role-permissions and wire a useAsyncCache variant.

docs/templates-python/concepts/teams-management.mdx (1)

220-241: Docs align well; small clarity tweaks suggested.

• In send_team_invitation, explicitly note that omitting permission_ids (or passing None/empty) applies the default member role.
• In examples, mention that the valid IDs come from get_team_role_permissions to avoid guesswork.

Apply:

@@
-    Send an invitation to join a team with optional role-based permissions
+    Send an invitation to join a team with optional role-based permissions.
+    If permission_ids is None or empty, the default member role is applied.
@@
-# Example usage - Send invitation with admin role
+# Example usage - Send invitation with admin role (IDs from get_team_role_permissions)

Also applies to: 248-267, 298-323, 331-348, 456-488

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

Learnt from: CR
PR: stack-auth/stack-auth#0
File: CLAUDE.md:0-0
Timestamp: 2025-08-24T18:36:37.712Z
Learning: Applies to apps/backend/src/app/api/latest/**/*.ts : Use the custom route handler system in the backend for consistent API responses

apps/backend/src/app/api/latest/team-member-profiles/crud.tsx (1)

206-215: Fix wrong user id field in getUserLastActiveAtMillis call.

Use db.projectUserId, not db.projectUser.projectUserId.

-      return prismaToCrud(db, await getUserLastActiveAtMillis(auth.project.id, auth.branchId, db.projectUser.projectUserId) ?? db.projectUser.createdAt.getTime(), perms.map(p => p.permissionId));
+      return prismaToCrud(
+        db,
+        (await getUserLastActiveAtMillis(auth.project.id, auth.branchId, db.projectUserId)) ?? db.projectUser.createdAt.getTime(),
+        perms.map(p => p.permissionId)
+      );

apps/backend/src/app/api/latest/team-invitations/accept/verification-code-handler.tsx (1)

33-35: Validate team_id as UUID for consistency.

Other routes use uuid() for team_id; align the schema here.

-  data: yupObject({
-    team_id: yupString().defined(),
+  data: yupObject({
+    team_id: yupString().uuid().defined(),
     permission_ids: yupArray(permissionDefinitionIdSchema.defined()).optional(),
   }).defined(),

apps/backend/src/app/api/latest/team-member-profiles/crud.tsx (2)

160-172: Align Read path with new helper keying.

Use the same team+user key to avoid future regressions.

-      const permissionMap = await fetchTeamMemberPermissions(
-        tx,
-        auth.tenancy.id,
-        db.teamId,
-        [db.projectUserId]
-      );
-
-      return prismaToCrud(
-        db,
-        await getUserLastActiveAtMillis(auth.project.id, auth.branchId, db.projectUserId) ?? db.projectUser.createdAt.getTime(),
-        permissionMap.get(db.projectUserId) || []
-      );
+      const permissionMap = await fetchTeamMemberPermissions(tx, auth.tenancy.id, [{ teamId: db.teamId, projectUserId: db.projectUserId }]);
+      const key = `${db.teamId}::${db.projectUserId}`;
+      return prismaToCrud(
+        db,
+        (await getUserLastActiveAtMillis(auth.project.id, auth.branchId, db.projectUserId)) ?? db.projectUser.createdAt.getTime(),
+        permissionMap.get(key) ?? []
+      );

---

206-213: DRY: reuse fetchTeamMemberPermissions in Update path.

Avoid duplicating permission queries.

-      const perms = await tx.teamMemberDirectPermission.findMany({
-        where: {
-          tenancyId: auth.tenancy.id,
-          projectUserId: db.projectUserId,
-          teamId: db.teamId,
-        },
-        select: { permissionId: true },
-      });
-
-      return prismaToCrud(db, await getUserLastActiveAtMillis(auth.project.id, auth.branchId, db.projectUser.projectUserId) ?? db.projectUser.createdAt.getTime(), perms.map(p => p.permissionId));
+      const pmap = await fetchTeamMemberPermissions(tx, auth.tenancy.id, [{ teamId: db.teamId, projectUserId: db.projectUserId }]);
+      const key = `${db.teamId}::${db.projectUserId}`;
+      return prismaToCrud(
+        db,
+        (await getUserLastActiveAtMillis(auth.project.id, auth.branchId, db.projectUserId)) ?? db.projectUser.createdAt.getTime(),
+        pmap.get(key) ?? []
+      );

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled by default for public repositories
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (1)

1504-1523: Return camelCase from getTeamRolePermissions and map the payload

Leaking snake_case (contained_permission_ids, is_paginated) from HTTP breaks JS client conventions and prior guidance. Map to containedPermissionIds and isPaginated.

-  async getTeamRolePermissions(): Promise<{ items: { id: string, description?: string, contained_permission_ids: string[] }[], is_paginated: false }> {
+  async getTeamRolePermissions(): Promise<{ items: { id: string; description?: string; containedPermissionIds: string[] }[]; isPaginated: false }> {
     const session = await this._getSession();
     const result = await this._interface.sendClientRequest(
       "/team-invitations/role-permissions",
       {
         method: "GET",
         headers: {
-          "Content-Type": "application/json",
+          "Accept": "application/json",
         },
       },
       session
     );
 
     if (!result.ok) {
       throw new Error(`Failed to get team role permissions: ${result.status} ${await result.text()}`);
     }
 
-    const data = await result.json();
-    return data;
+    const json = await result.json() as { items: { id: string; description?: string; contained_permission_ids: string[] }[]; is_paginated: false };
+    return {
+      items: json.items.map(({ id, description, contained_permission_ids }) => ({
+        id,
+        description,
+        containedPermissionIds: contained_permission_ids,
+      })),
+      isPaginated: false,
+    };
   }

packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts (3)

657-665: Default permissionIds to an empty array to avoid undefined at call sites

Safer for consumers and UI mapping.

       teamProfile: {
         displayName: crud.display_name,
         profileImageUrl: crud.profile_image_url,
-        permissionIds: crud.permission_ids,
+        permissionIds: crud.permission_ids ?? [],
       }

---

668-676: Also default invitation.permissionIds to []

Keeps the client shape stable even when backend omits the field.

       expiresAt: new Date(crud.expires_at_millis),
-      permissionIds: crud.permission_ids,
+      permissionIds: crud.permission_ids ?? [],

---

1511-1513: Use Accept for GET; Content-Type is unnecessary without a body

Minor HTTP header nit.

-        headers: {
-          "Content-Type": "application/json",
-        },
+        headers: { "Accept": "application/json" },

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

apps/e2e/tests/backend/endpoints/api/v1/team-invitations.test.ts (1)

559-579: Strengthen assertions and add edge case coverage.

The test validates basic response structure but could be more thorough:

• The conditional check at line 573 means the test passes with zero permissions, leaving structure assertions unverified.
• No validation of actual permission IDs or values returned.
• Missing error scenarios (e.g., unauthenticated requests, server access type behavior).

Consider these improvements:

 it("can fetch role permissions from role-permissions endpoint", async ({ expect }) => {
   await Auth.Otp.signIn();
 
   const response = await niceBackendFetch("/api/v1/team-invitations/role-permissions", {
     accessType: "client",
     method: "GET",
   });
 
   expect(response.status).toBe(200);
   expect(response.body).toHaveProperty('items');
   expect(response.body).toHaveProperty('is_paginated', false);
   expect(Array.isArray(response.body.items)).toBe(true);
+  expect(response.body.items.length).toBeGreaterThan(0);
 
-  // Check that each item has the correct structure
-  if (response.body.items.length > 0) {
-    const item = response.body.items[0];
+  // Validate every item has the correct structure
+  for (const item of response.body.items) {
     expect(item).toHaveProperty('id');
+    expect(typeof item.id).toBe('string');
+    expect(item.id.length).toBeGreaterThan(0);
     expect(item).toHaveProperty('contained_permission_ids');
     expect(Array.isArray(item.contained_permission_ids)).toBe(true);
   }
 });

Additionally, consider adding tests for:

• Unauthenticated access returning 401
• Server access type behavior
• Validation that known permission IDs (e.g., "team_admin") are present in the response

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

packages/template/src/components-page/account-settings/teams/team-member-invitation-section.tsx (3)

40-42: Remove debug console.log statements.

These debug statements should be removed before merging to production.

Apply this diff:

     const fetchRolePermissions = async () => {
       try {
-        console.log('Fetching role permissions...');
         const permissions = await project.listTeamPermissionDefinitions();
-        console.log('Role permissions fetched:', permissions);
         setRolePermissions(permissions);
       } catch (error) {

---

144-144: Remove duplicate watch destructuring.

watchForm is destructured but never used in the code, and watch is already destructured earlier in the same statement.

Apply this diff:

-  const { register, handleSubmit, formState: { errors }, watch, setValue, watch: watchForm } = useForm({
+  const { register, handleSubmit, formState: { errors }, watch, setValue } = useForm({

---

211-225: Make Select controlled to enable visual reset.

The Select component is currently uncontrolled (missing value prop), so calling setValue('role', '') after form submission doesn't reset the visual selection. Users will see the previously selected role still displayed after inviting a member.

Apply this diff to make the Select controlled:

-              <Select onValueChange={(value) => setValue('role', value)}>
+              <Select value={watch('role') ?? 'default'} onValueChange={(value) => setValue('role', value)}>
                 <SelectTrigger>

And update the default value and reset logic:

     defaultValues: {
       email: '',
-      role: '',
+      role: 'default',
     }

       // Reset form
       setValue('email', '');
-      setValue('role', '');
+      setValue('role', 'default');

packages/template/src/components-page/account-settings/teams/team-member-invitation-section.tsx (2)

65-86: Simplify getRoleDisplayName logic.

The current implementation creates a redundant Map that maps role.id to role.id, then performs lookups that simply return the original ID, followed by manual string comparisons for friendly names. This can be simplified significantly.

Apply this diff to streamline the logic:

   const getRoleDisplayName = (permissionIds: string[]) => {
-    if (permissionIds.length === 0) {
-      return t("Default member role");
-    }
-
     // Filter out permission IDs that start with $
     const filteredPermissionIds = permissionIds.filter(id => !id.startsWith('$'));
     if (filteredPermissionIds.length === 0) {
       return t("Default member role");
     }
 
-    // Map permission IDs to their IDs (instead of descriptions)
-    const roleMap = new Map(rolePermissions.map(role => [role.id, role.id]));
-
-
-    // Find the role that matches the permission IDs and return the ID
-    const matchingRoles = filteredPermissionIds.map(id => roleMap.get(id)).filter(Boolean);
-
-
-    if (matchingRoles.length > 0) {
-      const roleId = matchingRoles[0];
-      // Map common roles to friendly names
-      if (roleId === 'team_admin') return 'Admin';
-      if (roleId === 'team_member') return 'Member';
-      return roleId;
-    }
-
-    // Fallback to permission ID with mapping
-    const firstPermissionId = filteredPermissionIds[0];
-    if (firstPermissionId === 'team_admin') return 'Admin';
-    if (firstPermissionId === 'team_member') return 'Member';
-    return firstPermissionId;
+    // Map common roles to friendly names
+    const roleId = filteredPermissionIds[0];
+    if (roleId === 'team_admin') return 'Admin';
+    if (roleId === 'team_member') return 'Member';
+    return roleId;
   };

---

155-168: Consider extracting role permissions fetching to a custom hook.

The role permissions fetching logic is duplicated in two places (lines 37-52 and here). Extracting it to a custom hook like useTeamRolePermissions() would improve maintainability and reduce code duplication.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Learnt from: N2D4
Repo: stack-auth/stack-auth PR: 943
File: examples/convex/app/action/page.tsx:23-28
Timestamp: 2025-10-11T04:13:19.308Z
Learning: In the stack-auth codebase, use `runAsynchronouslyWithAlert` from `stackframe/stack-shared/dist/utils/promises` for async button click handlers and form submissions instead of manual try/catch blocks. This utility automatically handles errors and shows alerts to users.